Academic Portal API
This document describes the Academic Portal API for integrating with the JIIT Webportal. It covers authentication, session lifecycle, and endpoints for retrieving academic data such as attendance, exam events and schedules, registered subjects, and grades. It also documents request/response schemas, authentication requirements, and practical integration patterns for educational automation.
The Academic Portal API is implemented as a FastAPI application with a dedicated router for JIIT integration. The router exposes endpoints under the /api/pyjiit prefix. The service layer encapsulates the JIIT Webportal integration via a wrapper class that handles HTTP requests, session headers, and authentication.
https://webportal.jiit.ac.in:6011/StudentPortalAPI"]
Diagram sources
Section sources
Router: Defines endpoints for login, semesters, and attendance.
Service: Orchestrates session creation, data retrieval, and normalization.
Wrapper: Encapsulates JIIT Webportal HTTP calls, session headers, and authentication.
Models: Pydantic models for login responses and session payloads.
Key responsibilities:
Authentication: Username/password login with a prevalidated captcha token.
Session: Bearer token-based session with LocalName header.
Data Retrieval: Attendance, exam events, schedules, registered subjects, and grades.
Section sources
The API follows a layered architecture:
Presentation: FastAPI router defines endpoints and request/response models.
Application: Service translates API requests into Webportal operations.
Domain: Wrapper abstracts JIIT Webportal specifics and session management.
External System: JIIT Webportal API accessed over HTTPS.
Diagram sources
Authentication and Session Management#
Endpoint: POST /api/pyjiit/login
Purpose: Authenticate student credentials against the JIIT Webportal and return a session payload.
Request body:
username: string
password: string
Response body:
raw_response: includes regdata and client identifiers
regdata: top-level copy of registration data
institute, instituteid, memberid, userid, token, expiry, clientid, membertype, name
Authentication requirements:
Uses a prevalidated captcha token for login.
On success, the response includes a JWT-like token and session metadata.
Notes:
The wrapper constructs Authorization headers with a Bearer token and LocalName.
Diagram sources
Section sources
Semesters Discovery#
Endpoint: POST /api/pyjiit/semesters
Purpose: Retrieve the list of semesters registered for the authenticated student.
Request body: session_payload (full login response or raw response dict)
Response body: array of objects with registration_id and registration_code
Authentication: Requires a valid session (Bearer token and LocalName header).
Notes: Accepts either the full login response or the raw response dict.
Diagram sources
Section sources
Attendance Retrieval#
Endpoint: POST /api/pyjiit/attendence
Purpose: Fetch attendance for a specific semester.
Request body:
session_payload: session payload (wrapper or raw)
registration_code: optional string (e.g., “2025ODDSEM”); if omitted, a hardcoded value is used
Response body: array of objects with subject details and attendance percentage
Authentication: Requires a valid session.
Notes:
The implementation hardcodes a specific registration code and ID mapping.
Normalizes subject names by removing bracketed codes.
Diagram sources
Section sources
Exam Schedules and Academic Data#
While the primary router endpoints focus on login, semesters, and attendance, the underlying wrapper supports additional academic data retrieval. These capabilities are available for integration but are not exposed via the current router endpoints.
Available operations (not exposed by router):
Registered subjects and faculties for a semester
Exam events discovery
Exam schedule retrieval
Marks download (PDF)
Grade card retrieval
SGPA/CGPA data
Fee summary and pending charges
Subject choices
These operations rely on authenticated sessions and use the same header scheme (Bearer token + LocalName).
Section sources
The API components depend on each other as follows:
Router depends on PyJIIT Service for business logic.
Service depends on Webportal Wrapper for external API calls.
Wrapper depends on shared models for captcha and session headers.
Models define the shapes of login responses and session payloads.
Diagram sources
Section sources
Network latency dominates performance; minimize round-trips by batching related operations where feasible.
Reuse sessions: avoid repeated logins; persist and reuse the session payload.
Caching: cache normalized attendance lists and semesters for short intervals to reduce load.
Rate limiting: respect external API rate limits; implement retries with exponential backoff.
Streaming: for large downloads (e.g., marks PDF), stream responses to reduce memory usage.
Common issues and resolutions:
Session expired or unauthorized:
Symptom: 401 Unauthorized or session expiration errors.
Action: Re-authenticate using /api/pyjiit/login and obtain a fresh session payload.
Invalid or missing session payload:
Symptom: Errors when calling semesters or attendance endpoints.
Action: Ensure the session_payload is passed correctly (full login response or raw response dict).
Attendance not returned:
Symptom: Empty attendance list.
Action: Verify the hardcoded registration code mapping and that the student has attendance records for the selected semester.
Captcha-related login failures:
Symptom: Login errors during token generation.
Action: Confirm the prevalidated captcha token is included in the login flow.
Section sources
The Academic Portal API provides a focused interface for JIIT Webportal integration, enabling secure session-based access to academic data. By centralizing authentication and normalizing responses, it simplifies client integrations for attendance monitoring, exam scheduling, and broader academic workflows. Extending the router to expose additional endpoints (e.g., exam schedules, registered subjects) would further enable comprehensive automation scenarios.
Endpoint Reference#
POST /api/pyjiit/login
Description: Authenticate and return a session payload.
Request: { username: string, password: string }
Response: { raw_response, regdata, token, expiry, … }
POST /api/pyjiit/semesters
Description: List registered semesters for the authenticated student.
Request: { session_payload: object }
Response: [{ registration_id: string, registration_code: string }]
POST /api/pyjiit/attendence
Description: Retrieve attendance for a semester.
Request: { session_payload: object, registration_code?: string }
Response: [{ subjectcode: string, subjectcode_code: string, LTpercantage: string }]
Notes:
The attendance endpoint intentionally uses the misspelled “attendence” to match user expectations.
The semesters endpoint accepts either the full login response or the raw response dict.
Section sources
Authentication Details#
Header scheme:
Authorization: Bearer
LocalName: generated value
Token parsing:
The session payload includes a JWT-like token; the service extracts expiry from the payload when available.
Section sources
Data Privacy and Limitations#
Privacy:
Credentials and tokens are transmitted over HTTPS; handle tokens securely and avoid logging sensitive data.
Minimize retention of session payloads; invalidate on logout or after use.
Limitations:
The attendance endpoint currently uses a hardcoded registration code mapping; adjust as needed for different semesters.
Some endpoints require a valid session; ensure proper error handling for unauthorized or expired sessions.
Section sources
Client Integration Patterns#
Automated attendance monitoring:
Periodically call /api/pyjiit/login to refresh session, then /api/pyjiit/attendence to retrieve and compare attendance lists.
Academic workflow automation:
Use /api/pyjiit/semesters to discover semesters, then integrate with additional wrapper operations (e.g., exam events, schedules) to build a dashboard.
Error resilience:
Implement retry logic for transient network errors and handle 401 responses by re-authenticating.
[No sources needed since this section provides general guidance]